沐曦通用 GPU 与 MXMACA® 软件栈
用户指南
OG‑23018‑020‑F5_V26 2026‑04‑24

声明
版权所有 ©2023‑2026 沐曦集成电路（上海）股份有限公司。保留所有权利。
本文档中呈现的信息属于沐曦集成电路（上海）股份有限公司和/或其附属公司（以下统称为“沐曦股
份” ） ，非经沐曦股份事先书面许可，任何实体或个人均不得获得本文档的副本，且无权以任何方式处理
本文档，包括但不限于使用、复制、修改、合并、出版、发行、销售或传播本文档的部分或全部。
本文档内容仅供参考，不提供任何形式的、明示或暗示的保证，包括但不限于对适销性、适用于任何目
的和/或不侵权的保证。在任何情况下，沐曦股份均不对因本文档引起的、由本文档造成的、或与之相关
的任何索赔、损害或其他责任负责。
沐曦股份保留自行决定随时更改、修改、添加或删除本文档的部分或全部的权利。沐曦股份保留最终解
释权。
沐曦、MetaX 和其他沐曦图标是沐曦股份的商标。本文档中提及的所有其他商标和商品名称均为其各自
所有者的财产。
用户指南
目录
1 概述 1
1.1 适用产品 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2 产品简介 2
2.1 概述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.2 产品外观 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
3 安装与维护 3
3.1 用户须知 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.1.1 系统支持范围 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.1.2 服务器配置建议 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1.3 安装包说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.2 物理机上安装驱动和固件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
4 工具 7
4.1 mx‑smi 工具 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.2 mx‑report 工具 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.2.1 mx‑report 工具安装 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.2.2 mx‑report 工具使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.2.3 mx‑report 在容器中使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.2.4 mx‑report 命令介绍 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.2.4.1 通用选项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.2.4.2 日志导出选项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.2.4.3 日志级别操作选项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.2.4.4 日志模块操作选项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.2.4.5 环境信息收集 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2.4.6 环境信息对比 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2.4.7 附加选项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.2.5 mx‑report 工具卸载 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.3 mx‑exporter 工具 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5 维护管理 14
5.1 带内管理 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.2 带外管理 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
6 虚拟化支持 15
7 容器相关场景支持 16
7.1 官方 Docker 支持 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
7.1.1 获取 MXMACA 容器镜像 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
7.1.2 在 Docker 容器中使用板卡 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
OG‑23018‑020‑F5_V26 沐曦股份专有信息 i
用户指南
7.1.2.1 使用全部 GPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
7.1.2.2 使用指定 GPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
7.1.3 GPU 设备文件查询 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
8 附录 18
8.1 UMD 子模块说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
8.2 Firmware 子模块说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
8.3 术语/缩略语 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
OG‑23018‑020‑F5_V26 沐曦股份专有信息 ii
用户指南
图目录
图 2.1 曦云 C500 外观图 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
图 2.2 曦云 C500X 外观图 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
OG‑23018‑020‑F5_V26 沐曦股份专有信息 iii
用户指南
表目录
表 3.1 软硬件平台兼容列表 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
表 3.2 MXMACA SDK 软件包列表 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
表 4.1 日志级别说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
表 8.1 UMD 子模块说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
表 8.2 Firmware 子模块说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
OG‑23018‑020‑F5_V26 沐曦股份专有信息 iv
用户指南
更新记录
版本 日期 更新说明
V26 2026‑04‑24 更新以下章节：
3.1.1 系统支持范围
V25 2026‑03‑27 更新文档适用范围
V24 2026‑03‑09 更新以下章节：
4.2.4.3 日志级别操作选项
4.2.4.4 日志模块操作选项
新增以下章节：
8.1 UMD 子模块说明
8.2 Firmware 子模块说明
V23 2026‑01‑30 更新以下章节：
3.1.1 系统支持范围
4.2.4.2 日志导出选项
7.1 官方 Docker 支持
V22 2025‑11‑27 更新以下章节：
3.1.1 系统支持范围
4.2.4.2 日志导出选项
V21 2025‑10‑24 更新以下章节：
3.1.1 系统支持范围
V20 2025‑10‑09 新增 C600 系列产品信息
更新以下章节：
4.2.4.3 日志级别操作选项
4.2.4.4 日志模块操作选项
V19 2025‑09‑15 更新以下章节：
4.2.4.3 日志级别操作选项
4.2.4.4 日志模块操作选项
4.2.4.5 环境信息收集
4.2.4.7 附加选项
V18 2025‑08‑01 更新以下章节：
4.2.4.2 日志导出选项
V17 2025‑06‑25 更新以下章节：
2.2 产品外观
3.1.1 系统支持范围
4.2.4.2 日志导出选项
V16 2025‑04‑21 更新以下章节：
4.2.4.5 环境信息收集
下页继续
OG‑23018‑020‑F5_V26 沐曦股份专有信息 v
用户指南
表 1 – 续上页
版本 日期 更新说明
V15 2025‑03‑21 更新以下章节：
3.1.3 安装包说明
3.2 物理机上安装驱动和固件
4.2.4.3 日志级别操作选项
6 虚拟化支持
V14 2025‑02‑18 更新以下章节：
3.2 物理机上安装驱动和固件
V13 2024‑12‑20 更新以下章节：
4.2.4.2 日志导出选项
新增以下章节：
4.2.3 mx‑report 在容器中使用
4.2.4.5 环境信息收集
4.2.4.6 环境信息对比
V12 2024‑11‑08 更新以下章节：
3.1.1 系统支持范围
4.2.4.2 日志导出选项
4.2.4.3 日志级别操作选项
6 虚拟化支持
新增以下章节：
3.1.2 服务器配置建议
V11 2024‑09‑06 更新以下章节：
3.1.1 系统支持范围
3.1.3 安装包说明
3.2 物理机上安装驱动和固件
4.1 mx‑smi 工具
4.2.4.3 日志级别操作选项
4.3 mx‑exporter 工具
6 虚拟化支持
7 容器相关场景支持
新增以下章节：
4.2.4.4 日志模块操作选项
V10 2024‑08‑05 更新以下章节：
3 安装与维护
6 虚拟化支持
下页继续
OG‑23018‑020‑F5_V26 沐曦股份专有信息 vi
用户指南
表 1 – 续上页
版本 日期 更新说明
V09 2024‑06‑14 更新以下章节：
3.1.1 系统支持范围
3.1.3 安装包说明
3.2 物理机上安装驱动和固件
4.2.4.2 日志导出选项
6 虚拟化支持
V08 2024‑05‑15 更新以下章节：
2.2 产品外观
3.1.1 系统支持范围
3.2 物理机上安装驱动和固件
4.2.4.2 日志导出选项
6 虚拟化支持
V07 2024‑04‑10 更新以下章节：
3.1.1 系统支持范围
V06 2024‑03‑22 新增曦云 ® 系列 GPU 产品信息
更新以下章节：
2.2 产品外观
3.2 物理机上安装驱动和固件
6 虚拟化支持
7.1.2 在 Docker 容器中使用板卡
V05 2024‑02‑29 更新以下章节：
4.2.4.7 附加选项
6 虚拟化支持
V04 2024‑01‑31 更新以下章节：
6 虚拟化支持
V03 2024‑01‑10 更新以下章节：
4.2.4.3 日志级别操作选项
V02 2023‑12‑29 更新以下章节：
3.1.1 系统支持范围
3.1.3 安装包说明
3.2 物理机上安装驱动和固件
4.2.4.7 附加选项
新增以下章节：
6 虚拟化支持
V01 2023‑10‑16 首次发布
OG‑23018‑020‑F5_V26 沐曦股份专有信息 vii
用户指南
1 概述
本文档详细描述了沐曦通用 GPU 的运行环境配置，所需软件及工具的安装和使用方法，以及日常管理等
内容。
本文档主要适用于以下人员：
• 服务器管理员
• 沐曦通用 GPU 用户
1.1 适用产品
本文档适用于沐曦 MXC500 系列产品：曦云 ® C500、C500X、C550、C550‑PL、C588，曦思® N260，曦
索 ® X206；以及 MXC600 系列产品：曦云 ® C600，曦思 ® N300，曦索 ® X301、X302。
1 概述 沐曦股份专有信息 OG‑23018‑020‑F5_V26 | 1
用户指南
2 产品简介
2.1 概述
沐曦通用 GPU 产品，采用沐曦自主知识产权的 GPGPU 架构，提供强大的多精度混合算力、大容量高带
宽显存，支持 MetaXLink 卡间互联技术和新一代高速 IO 接口，配合全兼容主流 GPU 生态的 MXMACA ®
软件栈，可广泛应用于智算、通用计算和数据分析等场景。
2.2 产品外观
曦云 C500 的外观如图 2.1 所示。
图 2.1 曦云 C500 外观图
曦云 C500X 的外观图如图 2.2 所示。
图 2.2 曦云 C500X 外观图
2 产品简介 沐曦股份专有信息 OG‑23018‑020‑F5_V26 | 2
用户指南
3 安装与维护
若无特殊说明，本章是以曦云 C500 为例进行撰写。
3.1 用户须知
3.1.1 系统支持范围
目前已支持的 CPU 架构和内核版本，参见表 3.1。
表 3.1 软硬件平台兼容列表
CPU 架构 操作系统 内核版本 状态
x86_64 Ubuntu 18.04 5.4.0‑42‑generic 支持
5.4.0‑131‑generic
x86_64 Ubuntu 20.04 5.4.0‑144‑generic 支持
5.15.0‑58‑generic
x86_64 Ubuntu 22.04 5.15.0‑72‑generic 支持
5.15.0‑112‑generic
x86_64 Ubuntu 24.04 6.14.0‑27‑generic 支持
x86_64 CentOS 8 4.18.0‑240.el8.x86_64 支持
x86_64 CentOS 7 4.19.0‑1.el7.elrepo.x86_64 支持加载 Docker
Container 形式5.14.0
x86_64 BCLinux R8 U2 4.19.0‑240.23.11.el8_2.bclinux.x86_64 支持
x86_64 CC Linux 5.15.131‑2.cl9.x86_64 支持
x86_64 kylinv11 6.6.0‑32.7.v2505.ky11.x86_64 支持
x86_64 ALinux3 5.10.134‑13.1.al8.x86_64 支持
x86_64 CTYun 23.01 5.10.0‑136.12.0.86.ctl3.x86_64 支持
x86_64 KeyarchOS 5.8 4.18.0‑477.27.1.3.kos5.x86_64 支持
x86_64 RockyOS 9.2 5.14.0‑284.11.1.el9_2.x86_64 支持
x86_64 Debian 10 5.10.0‑0.deb10.28‑amd64 支持
x86_64 TencentOS 3.1 5.4.119‑19.0009.54 支持
x86_64 TencentOS 3.1 5.4.119‑19.0009.44 支持
x86_64 TencentOS 3.3 5.4.241‑24.0017.23 支持
x86_64 TencentOS 4.4 6.6.92‑34.1.t14.x86_64 支持
下页继续
3 安装与维护 沐曦股份专有信息 OG‑23018‑020‑F5_V26 | 3
用户指南
表 3.1 – 续上页
CPU 架构 操作系统 内核版本 状态
x86_64 CULinux‑3.0 5.10.0‑60.67.0.116.ule3.x86_64 支持
x86_64 CULinux‑4.0 6.6.0‑72.0.0.95.ule.x86_64 支持
x86_64 RHEL 9.6 5.14.0‑570.12.1.el9_6 支持
x86_64 RHEL 9.6 5.14.0‑570.54.1.el9_6 支持
x86_64 RHEL 9.4 5.14.0‑427.13.1.el9_4 支持
x86_64 RHEL 9.4 5.14.0‑427.96.1.el9_4 支持
aarch64 KylinV10 5.15.0‑1.10.6.v2307.ky10h.aarch64 支持
aarch64 kylinv11 6.6.0‑32.0.v2025.ky11.aarch64 支持
3.1.2 服务器配置建议
在 AI 模型训练和推理场景下，为了得到理想的多机通信性能，需要将服务器的 PCIe Max Payload 值设
置为 256。
某些服务器（比如同泰怡 Arm 服务器 TG657V2）的 PCIe Max Payload 缺省值不是 256，需要用户在服
务器 BIOS 中手动设置，或者联系服务器制造商。
3.1.3 安装包说明
为沐曦通用 GPU 提供的基础软件包由 Driver 和 MXMACA SDK 两部分组成。
• Driver 部分通过 run 安装文件发布，安装包说明参见《沐曦通用 GPU 驱动安装指南》中“安装包说
明”章节。
• MXMACA SDK 部分通过 tar 包发布，以 Ubuntu 系统为例，软件包内容参见表 3.2 。MXMACA SDK 的
安装参见《沐曦通用 GPU 快速上手指南》 。
表 3.2 MXMACA SDK 软件包列表
文件名 说明
commonLib_x.x.x.x_amd64.deb 沐曦通用 GPU 通用 lib 库
macainfo_x.x.x.x_amd64.deb 沐曦通用 GPU 软件 MXMACA 显示信息
mcanalyzer_x.x.x.x_amd64.deb 沐曦通用 GPU 工具库
mcblas_x.x.x.x_amd64.deb 沐曦通用 GPU BLAS 库，提供 BLAS API 接口
mccl_x.x.x.x_amd64.deb 沐曦通用 GPU 集合通信库，实现对 GPU 的多线程多进程运行
控制
mccompiler_x.x.x.x_amd64.deb 沐曦通用 GPU 编译器库，提供编译功能
mcthrust_x.x.x.x_amd64.deb 沐曦通用 GPU CUB/Thrust 库，提供 CUB/Thrust API 接口
下页继续
3 安装与维护 沐曦股份专有信息 OG‑23018‑020‑F5_V26 | 4
用户指南
表 3.2 – 续上页
文件名 说明
mcdnn_x.x.x.x_amd64.deb 沐曦通用 GPU DNN 库，提供 DNN API 接口
mceigen_x.x.x.x.amd64.deb 沐曦通用 GPU Eigen 库，提供 Eigen API 接口
mcfft_x.x.x.x_amd64.deb 沐曦通用 GPU FFT 库，提供 FFT API 接口
mcfile_x.x.x.x_amd64.deb 沐曦通用 GPU Direct Storage 库
mcimage_x.x.x.x.amd64.deb 沐曦通用 GPU G2D 库，提供 G2D API 接口
mcjpeg_x.x.x.x.amd64.deb 沐曦通用 GPU JPEG 库，提供 JPEG API 接口
mckernellib_x.x.x.x.amd64.deb 沐曦通用 GPU 核心库
mcmathlib_x.x.x.x.amd64.deb 沐曦通用 GPU 数学库
mcpti_x.x.x.x_amd64.deb 沐曦通用 GPU pti 库，提供 pti API 接口
mcrand_x.x.x.x_amd64.deb 沐曦通用 GPU random 库，提供 random API 接口
mcruntime_x.x.x.x.amd64.deb 沐曦通用 GPU 运行时库，提供 MXMACA API 接口
mcsolver_x.x.x.x_amd64.deb 沐曦通用 GPU SOLVER 库，提供 SOLVER API 接口
mcsolverit_x.x.x.x_amd64.deb 沐曦通用 GPU SolverIT 库，提供 SolverIT API 接口
mcsparse_x.x.x.x_amd64.deb 沐曦通用 GPU SPARSE 库，提供 SPARSE API 接口
mctlass_x.x.x.x.amd64.deb 沐曦通用 GPU Tlass 库，提供 Tlass API 接口
mctoolext_x.x.x.x.amd64.deb 沐曦通用 GPU 工具
mctracer_x.x.x.x.amd64.deb 沐曦通用 GPU 工具
metax‑docker_x.x.x_amd64.deb 沐曦通用 GPU docker 工具
mxcompute_x.x.x.x.amd64.deb 沐曦通用 GPU UMD 硬件抽象层
mxgpu_llvm_x.x.x.x.amd64.deb 沐曦通用 GPU 编译器
mxkw_x.x.x.x.amd64.deb mxkw 库，为与 KMD 交互的 user‑mode API
mxmaca‑install_x.x.x.x.amd64.deb 沐曦通用 GPU 辅助安装包
mxompi_x.x.x.x_amd64.deb 沐曦通用 GPU Open MPI 库，实现 GPU 并行计算
mxreport_x.x.x.x.amd64.deb mx‑report 工具，查询、设置日志级别，收集系统日志
mxucx_x.x.x.x_amd64.deb 沐曦通用 GPU UCX 库
sample_x.x.x.x_amd64.deb 沐曦通用 GPU sample 库，提供常用库的 sample
3 安装与维护 沐曦股份专有信息 OG‑23018‑020‑F5_V26 | 5
用户指南
3.2 物理机上安装驱动和固件
在物理机上安装驱动和固件， 参见《沐曦通用 GPU 驱动安装指南》中 “物理机上安装驱动和固件” 章节。
3 安装与维护 沐曦股份专有信息 OG‑23018‑020‑F5_V26 | 6
用户指南
4 工具
4.1 mx‑smi 工具
mx‑smi 工具的详细介绍，请参见《沐曦通用 GPU mx‑smi 使用手册》 。
4.2 mx‑report 工具
mx‑report 是沐曦通用 GPU 的日志管理工具，负责收集 KMD、UMD 和 Firmware 模块的日志，并提供
对 KMD、UMD 和 Firmware 模块的日志级别进行查询和设置的功能。
4.2.1 mx‑report 工具安装
沐曦通用 GPU 软件包安装过程中会默认安装 mx‑report 工具。软件包安装完成后，mx‑report 工具放置
在/opt/maca/bin/目录下。
4.2.2 mx‑report 工具使用方法
mx‑report 是一个 Linux 命令行工具，其调用遵守如下格式。
mx-report [ 选 项1 [ 参 数 1]] [ 参 数2] …
4.2.3 mx‑report 在容器中使用
若需在容器中使用 mx‑report 收集日志及环境信息，可在运行容器时传入以下参数：
docker run -it -d --device=/dev/dri --device=/dev/mxcd -v /sys/devices:/sys/
,→devices -v /sys/kernel:/sys/kernel -v /opt/maca:/opt/maca -v /var/log:/var/log -
,→v /usr/bin/kmd_diagnostic.sh:/usr/bin/kmd_diagnostic.sh -p 0.0.0.0:<hostPort>:
,→<container_port> --hostname <host_name> --privileged=true <image ID > -p
,→<container_port>
其中：
• 指定 -v /sys/kernel:/sys/kernel 及 --privileged=true 用于收集 xcore_config_id
• 指定 -v /var/log:/var/log 可在容器中收集日志
• 推荐使用 <container_ID>-主机名指定 <hostname>，便于后期区分设备
• 指定 -v /usr/bin/kmd_diagnostic.sh:/usr/bin/kmd_diagnostic.sh 可收集 KMD 诊断
相关信息
4 工具 沐曦股份专有信息 OG‑23018‑020‑F5_V26 | 7
用户指南
4.2.4 mx‑report 命令介绍
mx‑report 命令说明，可以通过在工作环境中执行 man mx-report 获取。
4.2.4.1 通用选项
-h, --help
打印使用帮助信息。
-v, --version
打印 mx‑report 的版本信息。
4.2.4.2 日志导出选项
mx-report
导出当前 GPU 所有模块日志及收集的环境信息，若不指定 --path，默认存放在当前目录下以“主机名
_ 时间戳”命名的文件夹中。
--path <target_path>
将导出的日志存放在指定目录，在收集完成后也会打印日志存放的地址。
--logmodule <umd|firmware|kmd|mccl|all>
导出指定模块的日志。若未指定，默认导出 KMD、UMD、Firmware 和 MCCL 所有日志。
-c/--continue
持续导出 KMD、UMD、Firmware 和 MCCL 的日志及收集的环境信息，可配合 --logmodule 持续导出
指定模块的日志。收集后的信息存放在当前目录下以“主机名 _ 时间戳”命名的文件夹中。
由于环境信息是一次性收集完毕，请勿较早地使用 Ctrl+C 停止以免信息收集不全。
--set-fwlog-capacity <log file size, log files number >
持续导出日志时，设置 Firmware 单个日志文件的大小和日志文件的数量。若未设置，默认为 20Mb，4
个文件。
-p/--pack <target file folder >
将导出的日志文件夹打包。
4 工具 沐曦股份专有信息 OG‑23018‑020‑F5_V26 | 8
用户指南
注解:
• 非持续导出时 KMD 日志文件是软链接。为保证打包的文件是软链接指向的源文件，推荐使用
mx-report -p 进行打包。
• 对于容器场景，一般不建议获取 KMD 日志，需要去对应物理机上获取。若确实需要在容器内获取
KMD 日志，需要在容器启动时将 /var/log 和 /proc 挂载到容器内部。
--dump-queue --pid xxx
当进程发生异常 Hang 住时，可导出异常进程的数据到当前目录下以 pid 命名的 json 文件中，以进一步
分析。其中 pid 可通过 mx-smi --show-process 获取，可用 -i 指定设备，默认收集所有设备信息。
注意：该命令暂不支持在 ARM 环境运行。
4.2.4.3 日志级别操作选项
表 4.1 日志级别说明
模块名称 日志级别
kmd 8: debug 指定收集调试信息及以上级别的日志
7: info 指定收集普通信息及以上级别的日志
6: notice 指定收集通知信息及以上级别的日志
5: warn 指定收集告警提示及以上级别的日志
4: error 指定收集一般错误及以上级别的日志
3: crit 指定收集严重错误及以上级别的日志
2: alert 指定收集告警错误及以上级别的日志
1: emerg 指定收集紧急错误级别日志
0: none 不收集日志
默认日志级别为 info，重启后恢复默认值
umd 6: verbose 指定收集所有信息
5: debug 指定收集调试信息及以上级别的日志
4: info 指定收集普通信息及以上级别的日志
3: warn 指定收集告警提示及以上级别的日志
2: error 指定收集一般错误及以上级别的日志
1: fatal 指定收集严重错误及以上级别的日志
0: none 不收集日志
默认日志级别为 error，重启后恢复默认值
下页继续
4 工具 沐曦股份专有信息 OG‑23018‑020‑F5_V26 | 9
用户指南
表 4.1 – 续上页
模块名称 日志级别
firmware 5: debug 指定收集调试信息及以上级别的日志
4: info 指定收集普通信息及以上级别的日志
3: warn 指定收集告警提示及以上级别的日志
2: error 指定收集一般错误及以上级别的日志
1: fatal 指定收集严重错误及以上级别的日志
0: none 不收集日志
默认日志级别为 info，重启后恢复默认值
--show-loglevel
显示 Firmware （MXC500 系列 ip： smp0， smp1， ccx0， ccx1， ccx2， xcore； MXC600 系列 ip： smp0，
smp1，xcore，eth） 、KMD 及运行中的 UMD 进程的日志级别。
--set-loglevel <moduleName,ipName,loglevel>
指定模块名和 ip（可先通过 --show-loglevel 查看）设置日志级别。其中 Firmware（MXC500 系列
ip：smp0，smp1，ccx0，ccx1，ccx2，xcore；MXC600 系列 ip：smp0，smp1，xcore，eth） ，有 0‑5
级别可设置；KMD 有 0‑8 级别可设置；UMD 有 0‑6 级别可以设置。
注解: 如要对 UMD 进程进行日志级别查询和设置操作，需在启动 UMD 进程前设置环境变量
MACA_PATH 和 MCTX_TARGET_INIT=true （拉起 rpc 服务） 。
4.2.4.4 日志模块操作选项
--show-logmodule
查询板卡 Firmware（C500 系列 ip：smp0，smp1，ccx0，ccx1，ccx2，xcore；C600 系列 ip：smp0，
smp1，xcore，eth）日志模块的状态，默认为 00000001，即 ip 第一个模块的日志开关为打开状态。
C588 支持使用 --die 进行分 die 显示。
--set-logmodule <ipName,state>
设置指定 ip （可通过--show-logmodule 查看） 日志模块状态：1 为打开；0 为关闭，关闭时不显示该
模块日志。 若设置f， 即为二进制 1111， 表示打开 4 个模块日志开关。 C588 支持使用--die 进行分 die
显示。每个 ip 共 28 个日志模块（0~0fffffff） 。本设置仅当 Firmware 该 ip 日志级别为5:debug 时生效。
1. 执行以下命令先查看 SMP0 的日志级别是否为 5:debug：
mx-report --show-loglevel
如果不是，执行以下命令设置 SMP0 的日志级别为 5:debug：
4 工具 沐曦股份专有信息 OG‑23018‑020‑F5_V26 | 10
用户指南
sudo mx-report --set-loglevel firmware,smp0,5
2. 执行以下命令开启 SMP0 前 5 个模块的日志：
sudo mx-report --set-logmodule smp0,0x1f
4.2.4.5 环境信息收集
mx-report --get-envinfo
仅收集当前设备的环境信息，存放在当前目录下以“主机名 _ 时间戳”命名的文件夹中。C588 支持使用
--die 进行分 die 显示。其中：
• envinfo.json 以 json 格式存储所有环境信息；
• envinfo.xlsx 仅存储键值对形式的环境信息；
• system_power_supply.txt存储系统电源信息；
• topo_info.txt存储设备 MetaXLink 拓扑信息、PCIe 信息以及 NUMA 信息等。
注解: 由于部分信息收集需 root 权限才能获取，因此需以 root 权限运行收集命令。
在容器中收集环境信息需在启动时增加参数 --privileged -v /sys/kernel:/sys/kernel ； 如需
同时收集日志信息，增加参数 -v /var/log:/var/log 。推荐增加参数 --hostname <hostname> ，
使用 <container_ID>-主机名以便知道收集的信息来自于哪个物理机。
4.2.4.6 环境信息对比
两台服务器之间信息对比
mx-report --compare envinfo1 .xlsx envinfo2 .xlsx
excel 各标签页对比信息如下：
• Commoninfo：对比所有指标值存在的差异。
• Server_info： 对比服务器的指标值存在的差异 （mem_used， mem_free， mem_buff， mem_available
除外） 。
• Env_virable_info：根据工具已定义的环境变量列表进行对比：
– 均包含某个环境变量，但值不同。
– 一个服务器包含该环境变量，另外一个服务器不包含。
• Pip_info：对所有的 python 安装包进行对比：
– 均包含某个安装包，但版本不同。
4 工具 沐曦股份专有信息 OG‑23018‑020‑F5_V26 | 11
用户指南
– 一个服务器有该安装包，另外一个服务器没有。
• Device_info：对比设备的指标值存在的差异（board_type，board_sn 除外） 。
同一服务器不同设备之间信息对比
mx-report --compare envinfo .xlsx
服务器上 GPU 设备数量大于 1 时，会对比不同 GPU 设备指标差异。
Device_info：对比设备的指标值存在的差异（board_type，board_sn 除外） 。
4.2.4.7 附加选项
-i ID, --index ID
指定板卡进行日志导出或日志级别查询和设置。如果没有指定，默认对全部板卡生效。ID 是从 0 开始的
自然数，可以通过 -L，--list 获取板卡的 ID 信息。
--die DIE_ID
指定 die 进行日志导出。如果没有指定，默认对所有 die 生效。
--pid pid
当设置 UMD 的日志级别时（ moduleName 为 umd ）需要指定该参数，表示对指定 pid 进行操作， pid
为 all 时对所有进程生效。
当立即导出或持续导出日志时，添加该参数会同时收集与进程 pid 相关的内存使用数据，存放在子目录
umd 下的 memInfo.csv 文件中。
4.2.5 mx‑report 工具卸载
沐曦通用 GPU 的驱动卸载后，mx‑report 工具会自动卸载。驱动卸载，参见《沐曦通用 GPU 驱动安装
指南》中“卸载驱动”章节。
在 Root 权限环境中， 也可以通过执行以下命令直接删除工作目录下的二进制执行文件来卸载 mx‑report
工具。
sudo rm /opt/maca/bin/mx-report
4 工具 沐曦股份专有信息 OG‑23018‑020‑F5_V26 | 12
用户指南
4.3 mx‑exporter 工具
mx‑exporter 工具的详细介绍，请参见《沐曦通用 GPU mx‑exporter 使用手册》和《沐曦通用 GPU
mx‑exporter Kubernetes 集群监控部署手册》 。
4 工具 沐曦股份专有信息 OG‑23018‑020‑F5_V26 | 13
用户指南
5 维护管理
5.1 带内管理
带内管理通过沐曦 mx‑smi 工具提供。mx‑smi 工具的使用，参见《沐曦通用 GPU mx‑smi 使用手册》 。
带内管理的功能有：提供命令行控制台供系统管理员查询系统软硬件配置和工作信息。
5.2 带外管理
BMC 提供带外管理功能， 包括查询沐曦通用 GPU 的配置信息， 生产信息， 时钟信息， 电源功率信息， 温
度信息，固件版本。通过 MCU，BMC 可以触发沐曦通用 GPU 的重启。
沐曦通用 GPU 的带外管理功能，参见相应系列产品的《带外管理手册》 。
5 维护管理 沐曦股份专有信息 OG‑23018‑020‑F5_V26 | 14
用户指南
6 虚拟化支持
虚拟化驱动安装和固件支持，参见《沐曦通用 GPU 驱动安装指南》中“虚拟化支持”章节。
6 虚拟化支持 沐曦股份专有信息 OG‑23018‑020‑F5_V26 | 15
用户指南
7 容器相关场景支持
沐曦通用 GPU 提供对 Docker 和 Kubernetes 的支持。Kubernetes 的详细介绍，参见《沐曦通用 GPU
云原生参考手册》 。
7.1 官方 Docker 支持
开发人员可以借助于容器引擎，运行预先构建好的容器镜像，快速建立软件开发或运行所需的环境。沐
曦通用 GPU 提供预构建的 MXMACA 容器镜像。开发人员仅需执行一条 docker run 命令就可获得一个
干净而完整的板卡开发环境。
在运行 MXMACA 容器镜像前，请确认环境满足以下条件：
• 已正确安装沐曦通用 GPU 的内核驱动。详细内容请参见 3 安装与维护。
• 已安装 Docker，Docker 版本 ≥19.03。
7.1.1 获取 MXMACA 容器镜像
MXMACA 容器镜像是以离线形式发布。用户可在随本文档发布的软件包中找到相关压缩包。本文档中
以 maca‑native‑3.5.3.0‑ubuntu22.04‑amd64.container .xz为例，用户应根据实际收到的软件包
版本对版本字段进行相应替换。
操作步骤
1. 执行以下命令，完成容器镜像的加载。
docker load < ./maca-native-3.5.3.0-ubuntu22.04-amd64.container.xz
7.1.2 在 Docker 容器中使用板卡
7.1.2.1 使用全部 GPU
操作步骤
1. 执行以下命令：
docker run -it --device=/dev/mxcd --device=/dev/dri --group-add video \
cr.metax-tech.com/library/maca-native:3.5.3.0-ubuntu22.04-amd64 /bin/bash
7 容器相关场景支持 沐曦股份专有信息 OG‑23018‑020‑F5_V26 | 16
用户指南
7.1.2.2 使用指定 GPU
正确安装内核驱动后，默认在/dev/dri 目录下为每一个 GPU 创建了一个 card 设备文件和一个 renderD
设备文件。通过绑定设备文件来指定期望使用的板卡。如何确认板卡的 ID 与 /dev/dri 目录下设备文件
之间的对应关系，请参见 7.1.3 GPU 设备文件查询。
操作步骤
例如，指定的板卡所对应的设备文件为/dev/dri/card1 和/dev/dri/renderD129。
1. 执行以下命令：
docker run -it --device=/dev/mxcd --device=/dev/dri/card1 \
--device=/dev/dri/renderD128 --group-add video \
cr.metax-tech.com/library/maca-native:3.5.3.0-ubuntu22.04-amd64 /bin/bash
7.1.3 GPU 设备文件查询
操作步骤
1. 使用 mx-smi 工具来查看。
mx-smi --show-sysinfo
输出如下：
mx-smi version: 2.3.1
================== MetaX System Management Interface Log ==================
Timestamp : Mon Jan 20 10:00:00 2026
Attached GPUs : 3
GPU#0 MXC500 0000:0e:00.0
Sys info
driver gpu id : 22597
node id : 2
render id : renderD128
card id : card1
GPU#1 MXC500 0000:11:00.0
Sys info
driver gpu id : 24589
node id : 3
render id : renderD129
card id : card2
7 容器相关场景支持 沐曦股份专有信息 OG‑23018‑020‑F5_V26 | 17
用户指南
8 附录
8.1 UMD 子模块说明
表 8.1 UMD 子模块说明
子模块名称 全称 含义
APP Application 应用程序
mcc MACA Compiler MXMACA 运行时编译库
mcr MACA Runtime MXMACA 运行时库
mctx MACA ToolsExt MXMACA 工具扩展库
mxc MetaX Compute 沐曦 GPU 计算代理库
pti MACA Profiling Tools Inter‑
face
MXMACA 性能分析工具接口库
mxkw MetaX Kernel Wrapper 沐曦 GPU 内核态驱动封装库
mxs MetaX Snapshot 沐曦 GPU 运行时快照
mxvpu MetaX Video Processing
Unit
沐曦 GPU 视频编解码库
maca.eid MACA Error Identification
Data
MXMACA 错误识别数据
8.2 Firmware 子模块说明
表 8.2 Firmware 子模块说明
子模块名称 全称 含义
SMP System Management Pro‑
cessor
系统管理微处理器
CCX Core CompleX 微处理器集合
XCORE MetaX Core 沐曦计算核心
ETH Ethernet 以太接口
8 附录 沐曦股份专有信息 OG‑23018‑020‑F5_V26 | 18
用户指南
8.3 术语/缩略语
术语/缩略语 全称 描述
ACS Access Control Services 访问控制服务
BIOS Basic Input/Output System 基本输入输出系统
BMC Baseboard Management Controller 基板管理控制器
Docker 一个开源的应用容器引擎
KMD Kernel‑Mode Driver 内核模式驱动程序
MCU Microcontroller Unit 微控制单元
MetaXLink 沐曦 GPU D2D 接口总线
MXMACA MetaX Advanced Compute Architec‑
ture
沐曦推出的 GPU 软件栈，包含了沐曦 GPU
的底层驱动、编译器、数学库及整套软件工
具套件
NUMA Non‑Uniform Memory Access 非一致性内存访问
PCI Peripheral Component Interconnect 一种连接主板和外部设备的总线标准
PCIe PCI Express 一种高速串行计算机扩展总线标准
P2P Peer‑to‑Peer PCIe P2P 是 PCIe 的一种特性，使两个 PCIe
设备之间可以直接传输数据
UMD User Mode Driver 用户模式驱动程序
8 附录 沐曦股份专有信息 OG‑23018‑020‑F5_V26 | 19
